Match dashboard TPS to the TUI indicator - #444

Implementation Plan

Problem analysis

The persisted per-turn TPS samples are already shared and correct. The mismatch is in aggregation and presentation:

• The TUI asks PerformanceTracker for the newest 100 samples for the active provider/model, asks the same tracker for the newest-10 versus up-to-10,000-sample median delta, gates output at three samples, and renders the approximation/count/trend metadata.
• The dashboard receives get_performance_stats.models, which comes from the separate 24-hour getAllRollingAverages() aggregation, then renders only the rounded median.
• Telegram also consumes the existing models array and explicitly describes it as “last 24h.” Replacing that array's semantics would fix the dashboard by changing an unrelated consumer. The RPC response should therefore gain additive TUI-parity data while retaining the existing 24-hour data for compatibility.

The parity data will be assembled in the coding-agent layer from the existing getRollingAverage() and getPerformanceDelta() calculators. The browser will select and format the active model's returned summary; it will not reproduce either calculation or its window rules.

Deliverables

1. Shared TUI-parity performance summaries

   • Add a tracker-level way to enumerate recorded provider/model identities and obtain each identity's rolling average and performance delta by delegating to the existing calculators.
   • Include identities represented in the retained performance log, not only identities with samples inside the current 24-hour window, so dashboard and TUI remain consistent for the same log.
   • Keep getAllRollingAverages() and its 24-hour semantics intact for existing consumers.

2. Additive RPC contract

   • Extend get_performance_stats with a clearly typed per-model parity section containing provider/model identity, the latest-100 rolling stats, and the recent-versus-baseline delta.
   • Preserve the existing models field and update the RPC handler/client types together.
   • Reuse named tracker/RPC types where practical instead of adding more inline shape duplication.

3. Dashboard TPS parity

   • Extend the dashboard protocol DTO for the new RPC data.
   • In the session details info bar, select the active provider/model's parity summary and apply the TUI rules: hide below three rolling samples; render ~<rounded median> tok/s [<count>]; append the rounded absolute delta, ↑/↓/→, median, and baseline count only when the shared delta has enough recent and baseline samples; force stable deltas to 0% as the TUI does.
   • Keep the calculation in the tracker/RPC layer. Dashboard code may format the returned semantic fields but must not calculate medians, deltas, thresholds, or sample windows.

4. Compatibility and documentation

   • Keep Telegram's current last-24-hour /stats behavior unchanged while accepting the additive RPC response.
   • Update public dashboard and RPC documentation to distinguish the retained 24-hour aggregate from the TUI-parity summary and document the dashboard's exact indicator semantics.
   • Update the root and coding-agent README descriptions where they mention dashboard/performance capabilities.

Acceptance criteria

• The dashboard's active-model TPS median comes from the same newest-100 calculation as the TUI.
• The dashboard presents the same approximation marker, rounded median, rolling count, trend percentage/direction, and baseline count as the TUI for the same tracker state.
• Dashboard TPS is absent when the active model has fewer than three valid samples.
• Trend metadata is absent when recent or baseline counts are insufficient; stable, above, and below trends follow the TUI's current rounding and arrow rules.
• Shared tracker calculators supply the rolling and delta values; no dashboard-side formula or sample-window implementation is introduced.
• Existing TUI behavior and its width handling remain unchanged.
• Existing Telegram last-24-hour output remains unchanged.
• Empty data and active-model mismatches remain safe and simply omit dashboard TPS.

Files to modify

Core and RPC

• packages/coding-agent/src/core/performance-tracker.ts — add the per-model parity summary/enumeration API that composes the existing rolling-average and delta calculators without changing the 24-hour aggregate.
• packages/coding-agent/src/modes/rpc/rpc-mode.ts — serialize both the existing 24-hour models and the new parity summaries.
• packages/coding-agent/src/modes/rpc/rpc-types.ts — type the additive response fields.
• packages/coding-agent/src/modes/rpc/rpc-client.ts — return the expanded typed response.

Dashboard

• packages/dashboard/src/shared/protocol.ts — mirror the expanded performance DTO.
• packages/dashboard/src/client/screens/session.tsx — consume and format the shared active-model parity summary in the details info bar.

Tests and fixtures

• packages/coding-agent/test/performance-tracker.test.ts — cover summary enumeration, latest-100 behavior, historical retained identities, empty data, and delegation to the existing calculators.
• packages/coding-agent/test/rpc-performance.test.ts — verify the additive RPC payload and client response while retaining the existing field.
• packages/dashboard/test/client/screens.test.tsx — replace the misleading plain-TPS assertion with exact parity cases for above, below, stable, insufficient-delta, fewer-than-three, empty, and wrong-model data.
• packages/dashboard/test/server.test.ts, packages/dashboard/test/runtime-pool.test.ts, and packages/dashboard/test/client/fleet-mobile.browser.test.ts — update all expanded performance-response mocks/route expectations.
• packages/telegram/test/commands.test.ts — update the RPC fixture and verify the existing last-24-hour section still uses the unchanged models data.
• packages/coding-agent/test/footer-width.test.ts — no behavior change expected; run as a required regression suite for the TUI source of truth.

Documentation

• README.md — keep the public performance/dashboard capability description accurate.
• packages/coding-agent/README.md — mention dashboard TPS parity where the dashboard capability is summarized.
• packages/dashboard/README.md — replace the vague “median tok/s” claim with the TUI-parity behavior.
• packages/coding-agent/docs/dashboard.md — document the exact session-info indicator.
• packages/coding-agent/docs/rpc.md — document the expanded response and the distinct semantics of its 24-hour and TUI-parity sections.

No new files are expected.

Testing approach

1. Run focused core/RPC/TUI tests:
   • npx vitest --run packages/coding-agent/test/performance-tracker.test.ts packages/coding-agent/test/rpc-performance.test.ts packages/coding-agent/test/footer-width.test.ts
2. Run focused dashboard and Telegram tests:
   • npx vitest --run packages/dashboard/test/client/screens.test.tsx packages/dashboard/test/server.test.ts packages/dashboard/test/runtime-pool.test.ts packages/telegram/test/commands.test.ts
3. Format/check every changed source, test, and documentation file with Biome where applicable.
4. Run npm run build after the code changes and before any manual testing against the compiled dashboard/dreb binaries.
5. Run the full npm test suite and npm run verify-workspace-links.
6. Manually inspect a built dashboard session at desktop and narrow/mobile widths with a populated performance log to confirm the longer indicator wraps cleanly and matches the TUI text for the same active model.

Risks and open questions

• RPC compatibility: Changing the meaning of models would silently alter Telegram. The additive response avoids that regression; all mocks and docs still need synchronized updates.
• Historical model discovery: The TUI reads the newest retained samples regardless of whether they fall in the last 24 hours. Parity enumeration must not derive solely from the 24-hour aggregate.
• Presentation parity: TUI colors are ANSI/theme-specific and cannot be reused directly in HTML. The shared semantic direction and the visible text/arrow/count rules should match; dashboard styling remains native CSS.
• Layout: The parity string is longer than the current dashboard text. Existing flex wrapping should handle it, but desktop and mobile widths need explicit regression checks.
• No blocking open question: The existing tracker APIs, RPC extension point, and dashboard consumer provide a focused path without changing sample recording or the TUI itself.

Plan created by mach6

Vitest coverage

View full coverage run

Plan Amendment — Unified TPS Semantics

The maintainer expanded the scope after implementation began: Telegram does not need to retain the 24-hour aggregation. Remove that path rather than carrying a compatibility payload.

Revised decisions:

• Delete getAllRollingAverages() and its 24-hour tests/documentation.
• Keep one RPC models collection, built exclusively by getAllModelSummaries() through the existing latest-100 rolling and latest-10-versus-up-to-10,000 delta calculators.
• Make the dashboard and Telegram /stats consume that same summary shape and apply the TUI sample gates, rounding, arrows, counts, and trend metadata.
• Update exported RPC types, all consumer fixtures/tests, and public documentation to describe one unified calculation.

This supersedes the original plan's additive compatibility section and Telegram-preservation risk.

Plan amended by mach6 after maintainer clarification

Progress Update

Implemented unified TPS semantics across the TUI, dashboard, Telegram, and RPC:

• Removed the 24-hour getAllRollingAverages() path and its tests.
• Added one per-model RPC summary shape produced by the existing latest-100 rolling and latest-10-versus-up-to-10,000 delta calculators.
• Updated the dashboard details pane and Telegram /stats to use the TUI's sample gates, rounding, arrows, counts, and median-delta metadata.
• Updated RPC exports, DTOs, all affected fixtures/tests, and root/package/feature documentation.
• Verified formatting, build, focused tests, the full test suite, workspace links, and built-dashboard desktop/mobile layouts with no horizontal overflow.

Commit: 312743c

Progress tracked by mach6

Code Review

Critical

None.

Important

None.

Suggestions

1. Telegram's TUI-parity formatting branches are untested (packages/telegram/src/commands/agent.ts:97-104, confidence 94). The /stats tests cover an above-trend path and the rolling-count gate, but not below-trend rounding/arrow, stable forced to 0%/→, or suppression of the trend suffix when either delta count is insufficient. These are explicit unified-semantics branches and should have table-driven assertions for the complete emitted model line.

2. The unified summary's 10,000-sample baseline cap is not tested (packages/coding-agent/test/performance-tracker.test.ts:223-233, confidence 85). Current summary tests stop at 102 entries, so they cannot catch a changed or removed cap. Add a summary-level case with more than 10,000 ordered samples that verifies baselineCount, recentCount, and the capped baseline median.

3. TPS presentation logic is duplicated between dashboard and Telegram (packages/dashboard/src/client/screens/session.tsx:78-93; packages/telegram/src/commands/agent.ts:92-103, confidence 92). The arrow map, stable-delta normalization, sample gates, rounding, and string template are effectively identical. A shared formatter would preserve output while reducing future semantic drift.

Strengths

• The new summary API delegates to the established latest-100 and latest-10-versus-up-to-10,000 calculators rather than duplicating statistical logic.
• RPC, dashboard, and Telegram types and consumers consistently use the unified model summary.
• Dashboard behavior mirrors the TUI gates and visible semantics, with strong coverage for active-model matching and presentation states.
• Empty, missing, and wrong-model paths are safely handled.
• Documentation is synchronized across root, coding-agent, dashboard, RPC, and Telegram surfaces.

Agents run: code-reviewer, error-auditor, test-reviewer, completeness-checker, simplifier

Reviewed by mach6

Review Assessment

Review comment

Classifications

Action Plan

1. Add table-driven Telegram /stats tests with exact emitted model-line assertions for below trend, stable trend, insufficient recent count, and insufficient baseline count.
2. Add a greater-than-10,000-entry getAllModelSummaries() test verifying a 10,000 baseline count, 10 recent samples, and a baseline median derived from the capped newest slice.

Assessment by mach6

Progress Update

Addressed the two genuine review findings:

• Added exact Telegram /stats output coverage for below and stable trends, plus insufficient recent and baseline sample gates.
• Added a 10,002-sample tracker regression test proving the newest-10,000 baseline cap, newest-10 recent window, and capped medians.
• Verified Biome, focused tests, the build, workspace links, and the commit-hook suite with live API tests disabled; all 5,554 hook tests passed.

Commit: 23264e7

Progress tracked by mach6